<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Multi-Threading</title>
</head>
<body>

<h2>Multi-Threading</h2>

<p>The JBehave <a
    href="javadoc/core/org/jbehave/core/embedder/Embedder.html">Embedder</a> allows concurrent execution of stories. 
    The multi-threading behaviour is controlled by setting the number of concurrent threads (which defaults to 1) via the <a
    href="javadoc/core/org/jbehave/core/embedder/EmbedderControls.html">EmbedderControls</a>, or equivalently via <a
    href="javadoc/core/org/jbehave/core/annotations/UsingEmbedder.html">@UsingEmbedder</a> or the 
    <a href="ant-tasks.html">Ant tasks</a> or <a href="maven-goals.html">Maven goals</a>.  
</p>

<p>The story execution can be configured to fail upon a timeout via the <a
    href="javadoc/core/org/jbehave/core/embedder/EmbedderControls.html">EmbedderControls</a>, or equivalently via <a
    href="javadoc/core/org/jbehave/core/annotations/UsingEmbedder.html">@UsingEmbedder</a> or the 
    <a href="ant-tasks.html">Ant tasks</a> or <a href="maven-goals.html">Maven goals</a>.</p>

<span class="followup">It is important to note that it's the entire story that is executed in one concurrent execution 
and that scenarios within the same story cannot be run concurrently.   For each story execution a <a href="story-timeouts.html">timeout</a> can be set 
via the same configuration mechanism used to set the number of threads.
</span>

<h2>Configuring the ExecutorService</h2>

<p>By default, the Embedder uses a fixed thread pool executor service, using the configured number of threads.  Users can
override the executor service using the Embedder's <a
    href="javadoc/core/org/jbehave/core/embedder/Embedder.html#useExecutorService(java.util.concurrent.ExecutorService)">useExecutorService(ExecutorService)</a> method.
 </p>

<h2>Enqueing a single story</h2>

<p>The Embedder API allow the enqueuing of a single story via the 
<a href="javadoc/core/org/jbehave/core/embedder/Embedder.html#enqueueStory(org.jbehave.core.failures.BatchFailures, org.jbehave.core.embedder.MetaFilter, java.util.List, java.lang.String, org.jbehave.core.model.Story)">enqueueStory</a> method.
This is used for example by the WebQueue to provide a simple web facade to running stories in an asynchronous way.
</p>

<p>The developer should take care that any static state shared between concurrently run stories should not introduce bugs or unwanted side effects.  Indeed it is the opinion of the JBehave  developer team that static state should be avoided.</p>

<p>It is possible that hundreds of stories could be run concurrently via this mechanism.  There are tradeoffs though.  Some other critical part of a system may fail of multiple threads are using it concurrently beyond its capacity.</p>

<h2>Examples</h2>

<p>Examples of use of multi-threading can be found in the 
 <a href="examples-modules.html">Threads Example</a> and the 
 <a href="tutorials.html">JBehave Tutorials</a>.</p>

</body>
</html>
